
<!DOCTYPE HTML>
<html lang="en" >
    <head>
        <meta charset="UTF-8">
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <title>API & Context · gitbook-official</title>
        <meta http-equiv="X-UA-Compatible" content="IE=edge" />
        <meta name="description" content="">
        <meta name="generator" content="GitBook 3.2.3">
        <meta name="author" content="snowdreams1006">
        
        
    
    <link rel="stylesheet" href="../../gitbook/style.css">

    
            
                
                <link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">
                
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-highlight/website.css">
                
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-search/search.css">
                
            
                
                <link rel="stylesheet" href="../../gitbook/gitbook-plugin-fontsettings/website.css">
                
            
        

    

    
        
        <link rel="stylesheet" href="../styles/website.css">
        
    
        
    
        
    
        
    
        
    
        
    

        
    
    
    
    
    <meta name="HandheldFriendly" content="true"/>
    <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
    <meta name="apple-mobile-web-app-capable" content="yes">
    <meta name="apple-mobile-web-app-status-bar-style" content="black">
    <link rel="apple-touch-icon-precomposed" sizes="152x152" href="../../gitbook/images/apple-touch-icon-precomposed-152.png">
    <link rel="shortcut icon" href="../../gitbook/images/favicon.ico" type="image/x-icon">

    
    <link rel="next" href="testing.html" />
    
    
    <link rel="prev" href="filters.html" />
    

    <style>
    @media only screen and (max-width: 640px) {
        .book-header .hidden-mobile {
            display: none;
        }
    }
    </style>
    <script>
        window["gitbook-plugin-github-buttons"] = {"buttons":[{"user":"snowdreams1006","repo":"gitbook-official","type":"star","size":"small"}]};
    </script>

    
        <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    
    
        <link rel="bookmark" href="/bookmark.ico" type="image/x-icon">
    
    
        <link rel="apple-touch-icon" sizes="152x152" href="/apple-touch-icon-152.png">
    
    
        <link rel="apple-touch-icon-precomposed" sizes="152x152" href="/apple-touch-icon-precomposed-152.png">
    
    
        
        <link rel="apple-touch-icon" sizes="120x120" href="/apple-touch-icon-120.png">
        
        <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon-180.png">
        
    
    
        
        <link rel="apple-touch-icon-precomposed" sizes="120x120" href="/apple-touch-icon-precomposed-120.png">
        
        <link rel="apple-touch-icon-precomposed" sizes="180x180" href="/apple-touch-icon-precomposed-180.png">
        
    

    </head>
    <body>
        
<div class="book">
    <div class="book-summary">
        
            
<div id="book-search-input" role="search">
    <input type="text" placeholder="Type to search" />
</div>

            
                <nav role="navigation">
                


<ul class="summary">
    
    
    
        
        <li>
            <a href="https://snowdreams1006.tech/" target="_blank" class="custom-link">blog</a>
        </li>
    
    

    
    <li class="divider"></li>
    

    
        
        <li class="header">Getting Started</li>
        
        
    
        <li class="chapter " data-level="1.1" data-path="../">
            
                <a href="../">
            
                    
                    About this documentation
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="1.2" data-path="../setup.html">
            
                <a href="../setup.html">
            
                    
                    Installation and Setup
            
                </a>
            

            
        </li>
    

    
        
        <li class="header">Your Content</li>
        
        
    
        <li class="chapter " data-level="2.1" data-path="../structure.html">
            
                <a href="../structure.html">
            
                    
                    Directory structure
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.2" data-path="../pages.html">
            
                <a href="../pages.html">
            
                    
                    Pages and Summary
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.3" data-path="../config.html">
            
                <a href="../config.html">
            
                    
                    Configuration
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.4" data-path="../lexicon.html">
            
                <a href="../lexicon.html">
            
                    
                    Glossary
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.5" data-path="../languages.html">
            
                <a href="../languages.html">
            
                    
                    Multi-Lingual
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html">
            
                    
                    Markdown
            
                </a>
            

            
            <ul class="articles">
                
    
        <li class="chapter " data-level="2.6.1" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#headings">
            
                    
                    Headings
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.2" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#paragraphs">
            
                    
                    Paragraphs
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.3" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#lists">
            
                    
                    Lists
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.4" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#links">
            
                    
                    Links
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.5" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#images">
            
                    
                    Images
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.6" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#blockquotes">
            
                    
                    Blockquotes
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.7" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#tables">
            
                    
                    Tables
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.8" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#code">
            
                    
                    Code
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.9" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#html">
            
                    
                    HTML
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.6.10" data-path="../syntax/markdown.html">
            
                <a href="../syntax/markdown.html#footnotes">
            
                    
                    Footnotes
            
                </a>
            

            
        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="2.7" data-path="../syntax/asciidoc.html">
            
                <a href="../syntax/asciidoc.html">
            
                    
                    AsciiDoc
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="2.8" data-path="../ebook.html">
            
                <a href="../ebook.html">
            
                    
                    eBook and PDF
            
                </a>
            

            
        </li>
    

    
        
        <li class="header">Customization</li>
        
        
    
        <li class="chapter " data-level="3.1" data-path="../templating/">
            
                <a href="../templating/">
            
                    
                    Templating
            
                </a>
            

            
            <ul class="articles">
                
    
        <li class="chapter " data-level="3.1.1" data-path="../templating/conrefs.html">
            
                <a href="../templating/conrefs.html">
            
                    
                    Content References
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.1.2" data-path="../templating/variables.html">
            
                <a href="../templating/variables.html">
            
                    
                    Variables
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.1.3" data-path="../templating/builtin.html">
            
                <a href="../templating/builtin.html">
            
                    
                    Builtin
            
                </a>
            

            
        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="3.2" data-path="./">
            
                <a href="./">
            
                    
                    Plugins
            
                </a>
            

            
            <ul class="articles">
                
    
        <li class="chapter " data-level="3.2.1" data-path="create.html">
            
                <a href="create.html">
            
                    
                    Create a plugin
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.2.2" data-path="hooks.html">
            
                <a href="hooks.html">
            
                    
                    Hooks
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.2.3" data-path="blocks.html">
            
                <a href="blocks.html">
            
                    
                    Blocks
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.2.4" data-path="filters.html">
            
                <a href="filters.html">
            
                    
                    Filters
            
                </a>
            

            
        </li>
    
        <li class="chapter active" data-level="3.2.5" data-path="api.html">
            
                <a href="api.html">
            
                    
                    API & Context
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="3.2.6" data-path="testing.html">
            
                <a href="testing.html">
            
                    
                    Test your plugin
            
                </a>
            

            
        </li>
    

            </ul>
            
        </li>
    
        <li class="chapter " data-level="3.3" data-path="../themes/">
            
                <a href="../themes/">
            
                    
                    Theming
            
                </a>
            

            
        </li>
    

    
        
        <li class="divider"></li>
        
        
    
        <li class="chapter " data-level="4.1" data-path="../faq.html">
            
                <a href="../faq.html">
            
                    
                    FAQ
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="4.2" data-path="../examples.html">
            
                <a href="../examples.html">
            
                    
                    Examples
            
                </a>
            

            
        </li>
    
        <li class="chapter " data-level="4.3" >
            
                <a target="_blank" href="https://github.com/GitbookIO/gitbook/blob/master/CHANGES.md">
            
                    
                    Release notes
            
                </a>
            

            
        </li>
    

    

    <li class="divider"></li>

    <li>
        <a href="https://www.gitbook.com" target="blank" class="gitbook-link">
            Published with GitBook
        </a>
    </li>
</ul>


                </nav>
            
        
    </div>

    <div class="book-body">
        
            <div class="body-inner">
                
                    

<div class="book-header" role="navigation">
    

    <!-- Title -->
    <h1>
        <i class="fa fa-circle-o-notch fa-spin"></i>
        <a href=".." >API & Context</a>
    </h1>
</div>




                    <div class="page-wrapper" tabindex="-1" role="main">
                        <div class="page-inner">
                            
<div id="book-search-results">
    <div class="search-noresults">
    
                                <section class="normal markdown-section">
                                

<div id="vip-container">
    <h1 id="context-and-apis">Context and APIs</h1>
<p>GitBooks provides different APIs and contexts to plugins. These APIs can vary according to the GitBook version being used, your plugin should specify the <code>engines.gitbook</code> field in <code>package.json</code> accordingly.</p>
<h4 id="book-instance">Book instance</h4>
<p>The <code>Book</code> class is the central point of GitBook, it centralize all access read methods. This class is defined in <a href="https://github.com/GitbookIO/gitbook/blob/master/lib/book.js" target="_blank">book.js</a>.</p>
<pre><code class="lang-js"><span class="hljs-comment">// Read configuration from book.json</span>
<span class="hljs-keyword">var</span> value = book.config.get(<span class="hljs-string">&apos;title&apos;</span>, <span class="hljs-string">&apos;Default Value&apos;</span>);

<span class="hljs-comment">// Resolve a filename to an absolute path</span>
<span class="hljs-keyword">var</span> filepath = book.resolve(<span class="hljs-string">&apos;README.md&apos;</span>);

<span class="hljs-comment">// Render an inline markup string</span>
book.renderInline(<span class="hljs-string">&apos;markdown&apos;</span>, <span class="hljs-string">&apos;This is **Markdown**&apos;</span>)
    .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">str</span>) </span>{ ... })

<span class="hljs-comment">// Render a markup string (block mode)</span>
book.renderBlock(<span class="hljs-string">&apos;markdown&apos;</span>, <span class="hljs-string">&apos;* This is **Markdown**&apos;</span>)
    .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">str</span>) </span>{ ... })
</code></pre>
<h4 id="output-instance">Output instance</h4>
<p>The <code>Output</code> class represent the output/write process.</p>
<pre><code class="lang-js"><span class="hljs-comment">// Return root folder for the output</span>
<span class="hljs-keyword">var</span> root = output.root();

<span class="hljs-comment">// Resolve a file in the output folder</span>
<span class="hljs-keyword">var</span> filepath = output.resolve(<span class="hljs-string">&apos;myimage.png&apos;</span>);

<span class="hljs-comment">// Convert a filename to an URL (returns a path to an html file)</span>
<span class="hljs-keyword">var</span> fileurl = output.toURL(<span class="hljs-string">&apos;mychapter/README.md&apos;</span>);

<span class="hljs-comment">// Write a file in the output folder</span>
output.writeFile(<span class="hljs-string">&apos;hello.txt&apos;</span>, <span class="hljs-string">&apos;Hello World&apos;</span>)
    .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{ ... });

<span class="hljs-comment">// Copy a file to the output folder</span>
output.copyFile(<span class="hljs-string">&apos;./myfile.jpg&apos;</span>, <span class="hljs-string">&apos;cover.jpg&apos;</span>)
    .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{ ... });

<span class="hljs-comment">// Verify that a file exists</span>
output.hasFile(<span class="hljs-string">&apos;hello.txt&apos;</span>)
    .then(<span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">exists</span>) </span>{ ... });
</code></pre>
<h4 id="page-instance">Page instance</h4>
<p>A page instance represent the current parsed page.</p>
<pre><code class="lang-js"><span class="hljs-comment">// Title of the page (from SUMMARY)</span>
page.title

<span class="hljs-comment">// Content of the page (Markdown/Asciidoc/HTML according to the stage)</span>
page.content

<span class="hljs-comment">// Relative path in the book</span>
page.path

<span class="hljs-comment">// Absolute path to the file</span>
page.rawPath

<span class="hljs-comment">// Type of parser used for this file</span>
page.type (<span class="hljs-string">&apos;markdown&apos;</span> or <span class="hljs-string">&apos;asciidoc&apos;</span>)
</code></pre>
<h4 id="context-for-blocks-and-filters">Context for Blocks and Filters</h4>
<p>Blocks and filters have access to the same context, this context is bind to the template engine execution:</p>
<pre><code class="lang-js">{
    <span class="hljs-comment">// Current templating syntax</span>
    <span class="hljs-string">&quot;ctx&quot;</span>: {
        <span class="hljs-comment">// For example, after a {% set message = &quot;hello&quot; %}</span>
        <span class="hljs-string">&quot;message&quot;</span>: <span class="hljs-string">&quot;hello&quot;</span>
    },

    <span class="hljs-comment">// Book instance</span>
    <span class="hljs-string">&quot;book&quot;</span> &lt;Book&gt;,

    <span class="hljs-comment">// Output instance</span>
    <span class="hljs-string">&quot;output&quot;</span>: <span class="xml"><span class="hljs-tag">&lt;<span class="hljs-name">Output</span>&gt;</span>
}
</span></code></pre>
<p>For example a filter or block function can access the current book using: <code>this.book</code>.</p>
<h4 id="context-for-hooks">Context for Hooks</h4>
<p>Hooks only have access to the <code>&lt;Book&gt;</code> instance using <code>this.book</code>.</p>
<pre><code class="lang-html">Author: snowdreams1006
Url: https://snowdreams1006.github.io/gitbook-official/en/plugins/api.html
Source: snowdreams1006&apos;s Gitbook
This article was originally published in&#x300C;snowdreams1006&apos;s Gitbook&#x300D;,Reproduced please indicate the source, thank you for cooperation!
</code></pre>
<p><img src="https://snowdreams1006.github.io/snowdreams1006-wechat-open.png" alt="https://snowdreams1006.github.io/snowdreams1006-wechat-open.png"></p>
<div id="gitalk-container"></div>
</div>

<hr>
<div class="btn-group btn-group-justified">
    
    <a class="btn" href="filters.html"><b>Previous:</b> Filters</a>
    
    
    <a class="btn" href="testing.html"><b>Next:</b> Test your plugin</a>
    
</div>

                                </section>
                            
    </div>
    <div class="search-results">
        <div class="has-results">
            
            <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
            <ul class="search-results-list"></ul>
            
        </div>
        <div class="no-results">
            
            <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
            
        </div>
    </div>
</div>

                        </div>
                    </div>
                
            </div>

            
                
                <a href="filters.html" class="navigation navigation-prev " aria-label="Previous page: Filters">
                    <i class="fa fa-angle-left"></i>
                </a>
                
                
                <a href="testing.html" class="navigation navigation-next " aria-label="Next page: Test your plugin">
                    <i class="fa fa-angle-right"></i>
                </a>
                
            
        
    </div>

    <script>
        var gitbook = gitbook || [];
        gitbook.push(function() {
            gitbook.page.hasChanged({"page":{"title":"API & Context","level":"3.2.5","depth":2,"next":{"title":"Test your plugin","level":"3.2.6","depth":2,"path":"plugins/testing.md","ref":"plugins/testing.md","articles":[]},"previous":{"title":"Filters","level":"3.2.4","depth":2,"path":"plugins/filters.md","ref":"plugins/filters.md","articles":[]},"dir":"ltr"},"config":{"plugins":["favicon-absolute","github-buttons","edit-link-plus","openwrite","copyright","mygitalk","multilingual-index"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"copyright":{"site":"https://snowdreams1006.github.io/gitbook-official","author":{"en":"snowdreams1006","zh":"雪之梦技术驿站"},"website":{"en":"snowdreams1006's Gitbook","zh":"雪之梦技术驿站"},"image":{"en":"https://snowdreams1006.github.io/snowdreams1006-wechat-open.png","zh":"https://snowdreams1006.github.io/snowdreams1006-wechat-open.png"}},"search":{},"edit-link-plus":{"label":{"en":"Edit This Page","zh":"编辑本页"},"base":{"snowdreams1006.github.io":"https://github.com/snowdreams1006/gitbook-official/edit/master","snowdreams1006.gitlab.io":"https://gitlab.com/snowdreams1006/gitbook-official/edit/master","snowdreams1006.gitee.io":"https://gitee.com/snowdreams1006/gitbook-official/edit/master"},"defaultBase":"https://github.com/snowdreams1006/gitbook-official/edit/master"},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"favicon-absolute":{"appleTouchIconMore":{"120x120":"/apple-touch-icon-120.png","180x180":"/apple-touch-icon-180.png"},"appleTouchIconPrecomposed152":"/apple-touch-icon-precomposed-152.png","appleTouchIconPrecomposedMore":{"120x120":"/apple-touch-icon-precomposed-120.png","180x180":"/apple-touch-icon-precomposed-180.png"},"favicon":"/favicon.ico","bookmark":"/bookmark.ico","appleTouchIcon152":"/apple-touch-icon-152.png"},"fontsettings":{"theme":"white","family":"sans","size":2},"highlight":{},"openwrite":{"blogId":"15702-1569305559839-744","name":"雪之梦技术驿站","qrcode":"https://snowdreams1006.github.io/snowdreams1006-wechat-public.jpeg","keyword":"vip"},"multilingual-index":{"enableSuper":false,"index":"index.html"},"github-buttons":{"buttons":[{"user":"snowdreams1006","repo":"gitbook-official","type":"star","size":"small"}]},"mygitalk":{"flipMoveOptions":{},"clientID":"3f62415a283d19cbd696","number":-1,"perPage":10,"proxy":"https://cors-anywhere.herokuapp.com/https://github.com/login/oauth/access_token","admin":["snowdreams1006"],"createIssueManually":false,"distractionFreeMode":false,"repo":"gitbook-official","owner":"snowdreams1006","enableHotKey":true,"clientSecret":"aed0e1db0620bf5d0e3a3f0225f801997ad74e58","pagerDirection":"last","labels":["Gitalk"]},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"theme":"default","author":"snowdreams1006","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"gitbook-official","language":"en","links":{"sidebar":{"blog":"https://snowdreams1006.tech/"}},"gitbook":"*","description":"gitbook document"},"file":{"path":"plugins/api.md","mtime":"2019-12-09T09:21:34.883Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2019-12-10T00:16:34.934Z"},"basePath":"..","book":{"language":"en"}});
        });
    </script>
</div>

        

    <script src="../../gitbook/gitbook.js"></script>
    <script src="../../gitbook/theme.js"></script>
    
        
        <script src="../../gitbook/gitbook-plugin-github-buttons/plugin.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-edit-link-plus/plugin.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-copyright/copyright.js"></script>
        
    
        
        <script src="https://cdn.bootcss.com/blueimp-md5/2.12.0/js/md5.min.js"></script>
        
    
        
        <script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-mygitalk/mygitalk.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-search/search-engine.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-search/search.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-sharing/buttons.js"></script>
        
    
        
        <script src="../../gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
        
    

<script src="https://my.openwrite.cn/js/readmore.js" type="text/javascript"></script>
<script>
var isMobile = navigator.userAgent.match(/(phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone)/i);
if (!isMobile) {
    var btw = new BTWPlugin();
    btw.init({
        "id": "vip-container",
        "blogId": "15702-1569305559839-744",
        "name": "雪之梦技术驿站",
        "qrcode": "https://snowdreams1006.github.io/snowdreams1006-wechat-public.jpeg",
        "keyword": "vip"
    });
}
</script>

    </body>
</html>

